/*
 * Copyright 2004 original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *    http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.jbfilter.core;

import java.util.Collection;
import java.util.Map;


/**
 * The contract for a container of filter components.
 * @author Marcus Adrian
 *
 * @param <E> the type of the objects the filter is conceived for
 */
public interface FilterComponentContainer<E> {
	/**
	 * Adds a component.
	 * @param fcomp the component
	 */
	void addFilterComponent(FilterComponent<E> fcomp);
	/**
	 * Gets the component looking-up by its id
	 * @param id
	 * @return the found component or {@code null} if not found
	 */
	FilterComponent<E> getFilterComponent(String id);
	/**
	 * The {@link FilterComponent}s attached to this object.
	 * @return
	 */
	Collection<FilterComponent<E>> getFilterComponents();
	/**
	 * A read-only view of the {@link FilterComponent}'s mapped by their id's.
	 * Every attempt of modification will result in an {@link UnsupportedOperationException}.
	 * Because the returned map is a view, it remains connected to the filter. So, if later another
	 * {@link FilterComponent} is added to the filter it will be seen by the map.
	 * In general, prefer {@link #getFilterComponent(String)} to this method. This should be considered as
	 * a convenience for script languages like EL which easily integrate {@link Map}'s but not methods with
	 * parameters (which is a good design decision).
	 * @return the components mapped by their own identifiers
	 * @throws UnsupportedOperationException when you try write operations, this is readonly!
	 */
	Map<String, FilterComponent<E>> getFilterComponentsById();
}